<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>chn</title>
    <link rel="stylesheet" type="text/css" href="csound.css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
    <link rel="up" href="OpcodesTop.html" title="Orchestra Opcodes and Operators" />
    <link rel="prev" href="checkbox.html" title="checkbox" />
    <link rel="next" href="chnclear.html" title="chnclear" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">chn</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="checkbox.html">Prev</a> </td>
          <th width="60%" align="center">Orchestra Opcodes and Operators</th>
          <td width="20%" align="right"> <a accesskey="n" href="chnclear.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="refentry">
      <a id="chn"></a>
      <div class="titlepage"></div>
      <a id="Indexchn" class="indexterm"></a>
      <div class="refnamediv">
        <h2>
          <span class="refentrytitle">chn</span>
        </h2>
        <p>chn — 
      Declare a channel of the named software bus.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp93661968"></a>
        <h2>Description</h2>
        <p>
      Declare a channel of the named software bus, with setting optional
      parameters in the case of a control channel. If the channel does not
      exist yet, it is created, with an inital value of zero or empty string.
      Otherwise, the type (control, audio, or string) of the existing channel
      must match the declaration, or an init error occurs. The input/output
      mode of an existing channel is updated so that it becomes the bitwise
      OR of the previous and the newly specified value.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp93663680"></a>
        <h2>Syntax</h2>
        <pre class="synopsis"> <span class="command"><strong>chn_k</strong></span> Sname, imode[, itype, idflt, imin, ima, ix, iy, iwidth, iheight, Sattributes]</pre>
        <pre class="synopsis"> <span class="command"><strong>chn_a</strong></span> Sname, imode</pre>
        <pre class="synopsis"> <span class="command"><strong>chn_S</strong></span> Sname, imode</pre>
      </div>
      <div class="refsect1">
        <a id="idp93731904"></a>
        <h2>Initialization</h2>
        <p>
      <span class="emphasis"><em>imode</em></span> -- sum of at least one of 1 for input and
      2 for output.
    </p>
        <p>
      <span class="emphasis"><em>itype</em></span> (optional, defaults to 0) -- channel subtype
      for control channels only. Possible values are:
      </p>
        <div class="itemizedlist">
          <ul class="itemizedlist" style="list-style-type: disc; ">
            <li class="listitem">
              <p>
            0: default/unspecified (<span class="emphasis"><em>idflt</em></span>, <span class="emphasis"><em>imin</em></span>,
            and <span class="emphasis"><em>imax</em></span> are ignored)
          </p>
            </li>
            <li class="listitem">
              <p>
            1: integer values only
          </p>
            </li>
            <li class="listitem">
              <p>
            2: linear scale
          </p>
            </li>
            <li class="listitem">
              <p>
            3: exponential scale
          </p>
            </li>
          </ul>
        </div>
        <p>
    </p>
        <p>
      <span class="emphasis"><em>idflt</em></span> (optional, defaults to 0) -- default value,
      for control channels with non-zero <span class="emphasis"><em>itype</em></span> only.
      Must be greater than or equal to <span class="emphasis"><em>imin</em></span>, and less than
      or equal to <span class="emphasis"><em>imax</em></span>.
    </p>
        <p>
      <span class="emphasis"><em>imin</em></span> (optional, defaults to 0) -- minimum value,
      for control channels with non-zero <span class="emphasis"><em>itype</em></span> only.
      Must be non-zero for exponential scale (<span class="emphasis"><em>itype</em></span> = 3).
    </p>
        <p>
      <span class="emphasis"><em>imax</em></span> (optional, defaults to 0) -- maximum value,
      for control channels with non-zero <span class="emphasis"><em>itype</em></span> only.
      Must be greater than <span class="emphasis"><em>imin</em></span>. In the case of exponential
      scale, it should also match the sign of <span class="emphasis"><em>imin</em></span>.
    </p>
        <p>
      <span class="emphasis"><em>ix</em></span> -- suggested x position for controller.
    </p>
        <p>
      <span class="emphasis"><em>iy</em></span> -- suggested y position for controller.
    </p>
        <p>
      <span class="emphasis"><em>iwidth</em></span> -- suggested width position for controller.
    </p>
        <p>
      <span class="emphasis"><em>iheight</em></span> -- suggested height position for controller.
    </p>
        <p>
      <span class="emphasis"><em>Sattributes</em></span> -- attributes for controller.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp93750240"></a>
        <h2>Notes</h2>
        <p>
      The channel parameters (<span class="emphasis"><em>imode</em></span>, <span class="emphasis"><em>itype</em></span>,
      <span class="emphasis"><em>idflt</em></span>, <span class="emphasis"><em>imin</em></span>, and <span class="emphasis"><em>imax</em></span>)
      are only hints for the host application or external software accessing the bus
      through the API, and do not actually restrict reading from or writing
      to the channel in any way. Also, the initial value of a newly created
      control channel is zero, regardless of the setting of <span class="emphasis"><em>idflt</em></span>.
    </p>
        <p>
      For communication with external software, using
      <a class="link" href="chnexport.html" title="chnexport"><em class="citetitle">chnexport</em></a> may be
      preferred, as it allows direct access to orchestra variables exported
      as channels of the bus, eliminating the need for using
      <a class="link" href="chnset.html" title="chnset"><em class="citetitle">chnset</em></a> and
      <a class="link" href="chnget.html" title="chnget"><em class="citetitle">chnget</em></a> to send or receive data.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp93758096"></a>
        <h2>Performance</h2>
        <p>
      <span class="command"><strong>chn_k</strong></span>, <span class="command"><strong>chn_a</strong></span>, and
      <span class="command"><strong>chn_S</strong></span> declare a control, audio, or string channel,
      respectively.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp93761456"></a>
        <h2>Example</h2>
        <p>
      The example shows the software bus being used as an asynchronous
      control signal to select a filter cutoff.  It assumes that an
      external program that has access to the API is feeding the values.
    </p>
        <div class="informalexample">
          <pre class="programlisting">
        <span class="ohdr">sr</span> <span class="op">=</span> 44100
        <span class="ohdr">kr</span> <span class="op">=</span> 100
        <span class="ohdr">ksmps</span> <span class="op">=</span> 1

        <span class="opc">chn_k</span> "cutoff", 1, 3, 1000, 500, 2000

        <span class="oblock">instr</span>   1
           kc   <span class="opc">chnget</span>    "cutoff"
           a1   <span class="opc">oscil</span>     p4, p5, 100
           a2   <span class="opc">lowpass2</span>  a1, kc, 200
                <span class="opc">out</span>       a2
        <span class="oblock">endin</span>
      </pre>
        </div>
      </div>
      <div class="refsect1">
        <a id="idp93772784"></a>
        <h2>Credits</h2>
        <p>
      </p>
        <table border="0" summary="Simple list" class="simplelist">
          <tr>
            <td>Author: Istvan Varga</td>
          </tr>
          <tr>
            <td>2005</td>
          </tr>
        </table>
        <p>
    </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="checkbox.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="OpcodesTop.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="chnclear.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">checkbox </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> chnclear</td>
        </tr>
      </table>
    </div>
  </body>
</html>
